/*
 * Copyright 2008-2009 Aying.Net Powered by Fuchun.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.aying.text;

import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle;

/**
 * 提供简单获取 {@code ResourceBundle} 资源包中的文本信息的各种方法。
 * <p />
 * 该接口中的方法多数参照 {@code com.opensymphony.xwork2.TextProvider} 接口。
 * 
 * @author Fuchun
 * @version 1.0, 2009-07-04
 */
public interface TextResources {

    /**
     * 确定给定 {@code key} 是否包含在资源键中。
     * 
     * @param key 资源 {@code key}。
     * @return 如果给定的 {@code key} 包含在资源键中，返回 {@code true}，否则 {@code false}。
     */
    boolean containsKey(String key);

    /**
     * 从资源中获得给定键的字符串。如果没有找到给定键的对象则返回空字符串。
     * <p />
     * <strong>注意：返回空字符串不一定代表没找到给定键的资源。可以先用 {@link #containsKey(String)}
     * 判断是否存在给定键。</strong>
     * 
     * @param key 资源 {@code key}。
     * @return 给定键的资源文本信息。如果未找到则返回空字符串。
     */
    String getText(String key);

    /**
     * 从资源中获得给定键的字符串。如果没有找到给定键的对象则返回给定的默认值 {@code defaultValue}。
     * 
     * @param key 资源 {@code key}。
     * @param defaultValue 未找到给定键的文本资源时返回的默认值。
     * @return 给定键的资源文本信息。如果未找到则返回给定的默认值 {@code defaultValue}。
     */
    String getText(String key, String defaultValue);

    /**
     * 获得默认语言环境下使给定键的指定参数的字符串。如果没有找到给定键的字符串，则返回空字符串。
     * 
     * @param key 资源 {@code key}。
     * @param args 给定的一组用于格式化信息（{@code java.util.MessageFormat}）的字符串。
     * @return 给定键的文本信息。如果未找则返回空字符串。
     */
    String getText(String key, Object... args);
    
    /**
     * 获得默认语言环境下使给定键的指定参数的字符串。如果没有找到给定键的字符串，则返回空字符串。
     * 
     * @param key 资源 {@code key}。
     * @param args 给定的一组用于格式化信息（{@code java.util.MessageFormat}）的字符串。
     * @return 给定键的文本信息。如果未找则返回空字符串。
     */
    String getText(String key, List<String> args);
    
    /**
     * 获得默认语言环境下使给定键的指定参数的字符串。如果没有找到给定键的字符串，则返回默认值 {@code defaultValue}。
     * 
     * @param key 资源 {@code key}。
     * @param defaultValue 未找到给定键的文本资源时返回的默认值。
     * @param args 给定的一组用于格式化信息（{@code java.util.MessageFormat}）的字符串。
     * @return 给定键的文本信息。如果未找则返回空默认值 {@code defaultValue}。
     */
    String getText(String key, String defaultValue, Object... args);
    
    /**
     * 获得默认语言环境下使给定键的指定参数的字符串。如果没有找到给定键的字符串，则返回默认值 {@code defaultValue}。
     * 
     * @param key 资源 {@code key}。
     * @param defaultValue 未找到给定键的文本资源时返回的默认值。
     * @param args 给定的一组用于格式化信息（{@code java.util.MessageFormat}）的字符串。
     * @return 给定键的文本信息。如果未找则返回空默认值 {@code defaultValue}。
     */
    String getText(String key, String defaultValue, List<String> args);
    
    /**
     * 使用指定的基本名称、默认的语言环境和调用者的类加载器获取资源包。
     * 
     * @param bundleName 资源包的基本名称，是一个完全限定类名。
     * @return 具有给定基本名称和默认语言环境的资源包。
     */
    ResourceBundle getBundle(String bundleName);
    
    /**
     * 设置要使用的 {@code ResourceBundle}。
     * 
     * @param bundle 要使用的 {@code ResourceBundle}。
     */
    void setBundle(ResourceBundle bundle);
    
    /**
     * 设置用于读取资源包的 {@code class} 对象。
     * 
     * @param clazz 用于读取资源包的 {@code class} 对象。
     */
    void setClazz(Class<?> clazz);
    
    /**
     * 获得当前的语言环境。
     * 
     * @return 当前的语言环境。
     */
    Locale getLocale();
    
    /**
     * 设置当前的语言环境。
     * 
     * @param locale 要设置的 当前的语言环境。
     */
    void setLocale(Locale locale);
}
